feat(rebalancer-sim): Add simulation harness for warp route rebalancer testing - #7903

Description

New typescript/rebalancer-sim package providing a fast real-time simulation framework for testing warp route rebalancers against synthetic transfer scenarios.

Key components:

• Multi-domain deployment: Deploy MockMailboxes, HypERC20Collateral warp tokens, and MockValueTransferBridge contracts on a single anvil instance with multiple domain IDs
• BridgeMockController: Intercepts bridge events and schedules async delivery with configurable delays, failure rates, jitter, and fees
• HyperlaneRunner: Simplified rebalancer implementation using weighted balance strategy with configurable tolerances
• ScenarioGenerator: Create transfer scenarios (unidirectional, random traffic, imbalance, surge patterns)
• KPICollector: Track completion rates, latencies (p50/p95/p99), rebalance volumes, per-chain metrics
• SimulationEngine: Orchestrates transfer execution, bridge delivery, and rebalancer polling
• RebalancerSimulationHarness: Top-level API for running simulations and comparing rebalancers

Architecture highlights:

• Uses 3 separate anvil accounts (deployer, rebalancer, bridge controller) to prevent nonce collisions
• Transaction queue in BridgeMockController serializes concurrent bridge deliveries
• Fast real-time execution (500ms bridge delays instead of real 30s+)
• Rebalancer observes only via JSON-RPC (no direct state access)

Drive-by changes

None

Related issues

None

Backward compatibility

Yes - this is a new package with no changes to existing code.

Testing

Unit Tests + Integration Tests

• 12 unit tests for ScenarioGenerator (serialization, validation, generation)
• 7 integration tests requiring anvil (RUN_ANVIL_TESTS=1):
  • Multi-domain deployment verification
  • Snapshot restore functionality
  • Full simulation runs with various scenarios (extreme drain, accumulate, whale transfers, balanced)

Run tests with:

cd typescript/rebalancer-sim
pnpm test                      # Unit tests only
RUN_ANVIL_TESTS=1 pnpm test   # All tests (requires anvil)

Summary by CodeRabbit

• New Features
  • Full simulation harness, runners (Simple, Production, NoOp), bridge/message mocks, KPI collector, timeline HTML export, and single-import public API.
• New Scenarios
  • Many scenarios added plus a scenario generator (stress, surge, imbalance, balanced, whale, inflight-guard, random, etc.).
• Tests
  • Extensive unit/integration suites and a matrix CI workflow to run and archive simulation results.
• Chores
  • Project configs, Mocha/ESLint/tsconfig/package.json, .gitignore, and tooling scripts.
• Documentation
  • Comprehensive README for the simulation module.
• Bug Fixes
  • Token transfer semantics adjusted to pulled-token behavior in tests.